feat: Introduce Tgpu(RenderPass/ComputePass/CommandEncoder) and remove the old callback based APIs - #2764

Pull request overview

This PR replaces the old callback-based experimental pass APIs with typed command encoder/pass abstractions (TgpuCommandEncoder, TgpuRenderPass, TgpuComputePass) to support batching, better state management, and deferred log/timestamp processing across submissions.

Changes:

• Introduces typed command encoders/passes and render bundle encoders, and rewires pipelines to target typed passes/encoders (or adopted raw WebGPU objects).
• Centralizes draw/dispatch state tracking (deduplication, “raw access disables dedup”, executeBundles reset behavior), and defers shader-log draining + timestamp resolve to encoder submission.
• Updates tests and docs to the new APIs; upgrades @webgpu/types catalog version.

Reviewed changes

Copilot reviewed 33 out of 34 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

✅ No new issues found.

Reviewed changes — introduces TgpuCommandEncoder, TgpuRenderPass, TgpuComputePass, and TgpuRenderBundleEncoder as typed wrappers around WebGPU's encoder/pass primitives, replacing the old callback-based beginRenderPass/beginRenderBundleEncoder APIs. Refactors pipeline dispatch to use the new typed passes, consolidates draw state management into drawState.ts, moves attachment types into attachments.ts, and adds a warnOnce utility for deduplicated warnings.

• Typed command encoder and passes — createCommandEncoder, beginRenderPass, beginComputePass on ExperimentalTgpuRoot; TgpuCommandEncoder, TgpuRenderPass, TgpuComputePass, TgpuRenderBundleEncoder new public types
• Pipeline dispatch refactor — both render and compute pipelines redirect through #execute → emitRenderDraw/emitComputeDispatch; #withPriors helper consolidates with() chain mutation
• Draw state and deduplication — RenderDrawState/ComputeDrawState classes with version counters; state re-applied on the raw pass only when changed or after unwrapping
• Attachment defaults — beginRenderPass derives loadOp/storeOp/depthClearValue defaults from texture format and view aspect; ColorAttachment/DepthStencilAttachment moved from render pipeline to attachments.ts
• Timestamp resolution — deferred to the encoder's beforeFinish hook via queueTimestampResolve; callbacks fire once per submission; repeated timed executions within one encoder warn
• warnOnce utility — WeakMap<object, Set<string>> deduplicates warnings per key; used for attachments, timestamps, logs, and guarded dispatch size mismatches
• TgpuGuardedComputePipeline — tracks batched dispatch sizes per encoder/pass; rejects differently-sized dispatches in one submission
• @webgpu/types bump — 0.1.69 → 0.1.71
• Old API removal — beginRenderPass/beginRenderBundleEncoder callbacks, RenderPass/RenderBundleEncoderPass types, applyPipelineState.ts, _lastAppliedRender/_lastAppliedCompute weak maps

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}

Awesome changes! 👏

✅ No new issues found.

Reviewed changes — commit 9a541a71 integrates the standalone warnOnce utility into TgpuLogger, switches all call sites to use logger.warnOnce('suspicious', ...), and adds the missing createCommandEncoder surface to the WebGL fallback.

• warnOnce in TgpuLogger — shared/warnOnce.ts deleted; TgpuLogger gains warnOnce(type, key, tag, ...args) with the same dedup semantics plus warning-type gating (silenced in production)
• Per-root dedup for finish() — key changed from the encoder instance to root, so the "use submit()" warning fires at most once per root
• WebGL fallback — TgpuRootWebGL now has createCommandEncoder() that throws WebGLFallbackUnsupportedError
• Test hardening — vi.spyOn → using in two compute pipeline tests; new test for per-root warning dedup across encoders; new warnOnce unit tests for the logger (once-per-key-and-tag, disabled-type behavior)

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}

Great changes! I think the new API is intuitive.

I didn't manage to review the entire thing.

✅ No new issues found.

Reviewed changes — commit 8de9da9c builds on the typed encoder/pass API by integrating buffers with command encoders, adding typed indirect draw/dispatch support, simplifying the guarded compute pipeline contract, and updating docs/examples.

• Buffer encoder integration — TgpuBuffer.clear(encoder?) and TgpuBuffer.copyFrom(src, encoder?) now record into an optional TgpuCommandEncoder instead of always submitting immediately; tests verify the command is deferred until encoder.submit()
• Typed indirect dispatches and draws — dispatchWorkgroupsIndirect, drawIndirect, and drawIndexedIndirect accept TgpuBuffer<...> & IndirectFlag plus a PrimitiveOffsetInfo or numeric offset; a shared resolveIndirectOffset helper validates alignment, buffer bounds, and contiguous-byte padding in pipelineUtils.ts
• Guarded pipeline simplification — TgpuGuardedComputePipeline.with() now only accepts bind groups and dispatches immediately on each dispatchThreads() call; the previous batched-size tracking for encoders/passes was removed, matching the documented limitation
• Genetic-racing example rewrite — switched from guarded pipelines to regular compute pipelines batched into typed compute passes, avoiding the guarded-pipeline overhead while using the new encoder APIs
• Docs and examples — updated buffers.mdx, pipelines.mdx, and timestamp-queries.mdx with the new encoder examples; migrated render-bundles, render-bundles-with, and simple-shadow examples to the typed command encoder/pass flow
• WebGL fallback — renamed the unsupported-method stubs from the old callback API to createCommandEncoder/createRenderBundleEncoder
• Test hardening — replaced toBeCalled* with toHaveBeenCalled* across the new command-encoder tests and added using for console.warn spies; buffer tests cover the new encoder variants

Validation run: pnpm vitest run --project=!browser packages/typegpu/tests/{buffer,commandEncoder,computePipeline,renderPipeline,guardedComputePipeline,root}.test.ts (199 tests passed) and pnpm --filter typegpu test:types both pass.

  ^{｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

✅ No new issues found.

Reviewed changes — the latest push (8de9da9c → 3f1f2d16) is a rebase onto a newer main. The PR-specific typed encoder/pass changes are unchanged from the prior review.

I re-ran the targeted test suite on the new head and verified the same behavior:

• pnpm vitest run --project=!browser packages/typegpu/tests/{buffer,commandEncoder,computePipeline,renderPipeline,guardedComputePipeline,root}.test.ts — 199 tests passed
• pnpm --filter typegpu test:types — passes

No new PR-specific concerns.

  ^{｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}